<html>
<head>
<title>
Netlab Reference Manual kmeans
</title>
</head>
<body>
<H1> kmeans
</H1>
<h2>
Purpose
</h2>
Trains a k means cluster model.

<p><h2>
Synopsis
</h2>
<PRE>
centres = kmeans(centres, data, options)
[centres, options] = kmeans(centres, data, options)
[centres, options, post, errlog] = kmeans(centres, data, options)
</PRE>


<p><h2>
Description
</h2>

<CODE>centres = kmeans(centres, data, options)</CODE>
uses the batch K-means algorithm to set the centres of a cluster model.
The matrix <CODE>data</CODE> represents the data
which is being clustered, with each row corresponding to a vector.
The sum of squares error function is used.  The point at which
a local minimum is achieved is returned as <CODE>centres</CODE>.  The
error value at that point is returned in <CODE>options(8)</CODE>.

<p><CODE>[centres, options, post, errlog] = kmeans(centres, data, options)</CODE>
also returns the cluster number (in a one-of-N encoding) for each data
point in <CODE>post</CODE> and a log of the error values after each cycle in
<CODE>errlog</CODE>.
  
The optional parameters have the following interpretations.

<p><CODE>options(1)</CODE> is set to 1 to display error values; also logs error 
values in the return argument <CODE>errlog</CODE>.
If <CODE>options(1)</CODE> is set to 0,
then only warning messages are displayed.  If <CODE>options(1)</CODE> is -1,
then nothing is displayed.

<p><CODE>options(2)</CODE> is a measure of the absolute precision required for the value
of <CODE>centres</CODE> at the solution.  If the absolute difference between
the values of <CODE>centres</CODE> between two successive steps is less than
<CODE>options(2)</CODE>, then this condition is satisfied.

<p><CODE>options(3)</CODE> is a measure of the precision required of the error
function at the solution.  If the absolute difference between the
error functions between two successive steps is less than
<CODE>options(3)</CODE>, then this condition is satisfied.
Both this and the previous condition must be
satisfied for termination.

<p><CODE>options(14)</CODE> is the maximum number of iterations; default 100.

<p><h2>
Example
</h2>
<CODE>kmeans</CODE> can be used to initialise the centres of a Gaussian 
mixture model that is then trained with the EM algorithm.
<PRE>

[priors, centres, var] = gmmunpak(p, md);
centres = kmeans(centres, data, options);
p = gmmpak(priors, centres, var);
p = gmmem(p, md, data, options);
</PRE>


<p><h2>
See Also
</h2>
<CODE><a href="gmminit.htm">gmminit</a></CODE>, <CODE><a href="gmmem.htm">gmmem</a></CODE><hr>
<b>Pages:</b>
<a href="index.htm">Index</a>
<hr>
<p>Copyright (c) Ian T Nabney (1996-9)


</body>
</html>